\renewcommand{\rule}[1]{$\langle #1\rangle$}

In this section, we first explain the main idea of 2APL and present
its basic programming constructs. Then, we explain the idea of
modules in 2APL and present the module related programming
constructs.

\begin{chapter}{The 2APL Language}\label{chap:language}

    \begin{section}{Multi-agent system specification}
        2APL is a multi-agent programming language that provides programming
        constructs to specify both multi-agent systems and individual
        agents. The configuration of a multi-agent system is specified in XML
        format using the tag {\tt apaplmas}. The specification is
        included in a file with the {\tt .mas} extension.
        Within this tag, agents and the environments in which the agents operate are
        specified. The environment tags are optional since multi-agent systems
        may consist of only individual agents without any external
        environment. An example of a multi-agent system
        configuration is illustrated in Figure~\ref{fig:masfile}.

\begin{figure}[ht]
\begin{verbatim}
<apaplmas>

    <environment name="blockworld" file="blockworld.jar">
        <parameter key="gridWidth" value="18" />
        <parameter key="gridHeight" value="18" />
        <parameter key="entities" value="2" />
    </environment>

    <agent name="harry" file="harry.2apl" />
    <agent name="sally" file="sally.2apl" />

</apaplmas>
\end{verbatim}
\caption{The specification of the {\tt harry and sally} multi-agent
system system.}\label{fig:masfile}
\end{figure}

        The individual agents are specified using the tag {\tt
        agent} with two mandatory attributes: {\tt name} and
        {\tt file}. The name will be used to identify the agent in the multi-agent system and the
        file (with {\tt .2apl} extension) is used to define the
        initial state of the agent (see below for the syntax of {\tt .2apl} files).
        In addition, one can use the tag {\tt beliefs} within the
        tag {\tt agent} in order to extend the agent's beliefs with additional facts.
        For example, the following is the specification of the agent {\tt harry} from the
        above multi-agent configuration, extended with some additional
        beliefs stored in the file {\tt friends.pl}. We assume this
        file contains the identity of agents who are friends of {\tt harry}.

        \begin{verbatim}
            <agent name="harry" file="harry.2apl" />
                <beliefs file="friends.pl" shadow="true"/>
            </agent>
        \end{verbatim}

        This option is specially useful for
        creating various, but different, agents from one and the same {\tt .2apl}
        file. These agents differ from each other with respect to the additional facts.
        The {\tt beliefs} tag has an mandatory attribute {\tt file}
        referring to a Prolog file with a {\tt .pl} extension. The
        tag {\tt beliefs} can use an optional {\tt shadow}
        attribute with values {\tt true} or {\tt false}. The first
        value causes the additional beliefs to be visible in the 2APL
        user interface, while the second value hides the additional beliefs
        from the user interface. The tag {\tt beliefs} is not used
        in the {\tt harry and sally} example.

        The environments are specified using the tag {\tt
        environment} which has two mandatory attributes: {\tt name} and
        {\tt file}. The first attribute defines the name of the
        environment (used by agents to perform their actions) and
        the second attribute defines a jar-file that implements the
        environment (see section \ref{chap:environment} for how an
        implemented environment can be used). The environments can be initialized with
        specific parameters, depending on their implementations, using
        the tag {\tt parameters} each with two mandatory attributes:
        {\tt key} and {\tt value}. In the {\tt harry and sally}
        example, the parameters determine the size of the {\tt
        blockworld} environment and the number of agents expected to
        appear in that environment.
    \end{section}


    The 2APL programming language for individual agents supports the integration of declarative
    concepts such as belief and goals with imperative style programming such as
    events and plans. This section presents the complete syntax of 2APL (the file
    with {\tt .2apl} extension), which is
    specified using the EBNF notation. This specification includes the
    module related programming constructs generated by the nonterminal
    \rule{moduleaction} and its related production rules. We first
    explain the non-module programming constructs, and then explain
    the module related programming constructs.
    In this specification, as illustrated below,
    we use $\langle atom\rangle$ to denote a Prolog like
    atomic formula starting with lowercase letter, $\langle Atom\rangle$ to denote
    a Prolog like atomic formula starting with a capital letter, $\langle
    ident\rangle$ to denote a string and $\langle Var\rangle$ to denote a string
    starting with a capital letter. We use \bla{ground\_atom} to denote a grounded
    atomic formula. Note that the question mark '{\tt ?}' used in \bla{testbelief}
    is a syntactic entity of the 2APL language, while other question marks are
    used as elements of the EBNF notation indicating the optional choice.

    \begin{tabbing}
    \rule{beliefupdatename}
        S\= :== \=\kill
        \rule{APAPL} \> = \>\{\texttt{"Include:"} \rule{includes}\\
            \>$\mid$\> \texttt{"BeliefUpdates:"} \rule{beliefupdates}\\
            \>$\mid$\> \texttt{"Beliefs:"} \rule{beliefs}\\
            \>$\mid$\> \texttt{"Goals:"} \rule{goals}\\
            \>$\mid$\> \texttt{"Plans:"} \rule{plans}\\
            \>$\mid$\> \texttt{"PG-rules:"} \rule{pgrules }\\
            \>$\mid$\> \texttt{"PC-rules:"} \rule{pcrules }\\
            \>$\mid$\> \texttt{"PR-rules:"} \rule{prrules }\}*;\\
        \rule{includes} \> = \> \rule{include}+;\\
        \rule{include} \> = \> \rule{ident} \texttt{".2apl"}; \\
        \rule{beliefupdates} \> = \> \rule{beliefupdate}+;\\
        \rule{beliefupdate} \> = \> \texttt{"\{"} [\rule{belquery}] \texttt{"\}"} \rule{beliefupdatename} \texttt{"\{"} \rule{literals} \texttt{"\}"};\\
        \rule{beliefupdatename} \> = \> \rule{upperatom};\\
        \rule{beliefs} \> = \> \rule{belief}+;\\
        \rule{belief} \> = \> \rule{ground\_atom}\texttt{"."}\\
            \>$\mid$\> \rule{atom} \texttt{":-"} \rule{literals} \texttt{"."};\\
        \rule{goals} \> = \> \rule{goal} \{\texttt{","} \rule{goal}\};\\
        \rule{goal} \> = \> \rule{ground\_atom} \{\texttt{"and"} \rule{ground\_atom}\};\\
        \rule{baction} \> = \> \texttt{"skip"}\\
            \>$\mid$\> \rule{beliefupdatename}\\
            \>$\mid$\> \rule{sendaction}\\
            \>$\mid$\> \rule{externalaction}\\
            \>$\mid$\> \rule{abstractaction}\\
            \>$\mid$\> \rule{test}\\
            \>$\mid$\> \rule{adoptgoal}\\
            \>$\mid$\> \rule{dropgoal}\\
            \>$\mid$\> \rule{createaction}\\
            \>$\mid$\> \rule{releaseaction}\\
            \>$\mid$\> \rule{moduleaction};\\
        \rule{plans} \> = \> \rule{plan} \{\texttt{","} \rule{plan}\};\\
        \rule{plan} \> = \> \rule{baction}\\
            \>$\mid$\> \rule{sequenceplan}\\
            \>$\mid$\> \rule{ifplan}\\
            \>$\mid$\> \rule{whileplan}\\
            \>$\mid$\> \rule{atomicplan}\\
            \>$\mid$\> \rule{scopeplan};\\
        \rule{sendaction} \> = \> \texttt{"send("} \rule{iv} \texttt{","} \rule{iv} \texttt{","} \rule{atom} \texttt{")"}\\
            \>$\mid$\> \texttt{"send("} \rule{iv} \texttt{","} \rule{iv} \texttt{","} \rule{iv} \texttt{","} \rule{iv} \texttt{","} \rule{atom} \texttt{")"};\\
        \rule{externalaction} \> = \> \texttt{"@"} \rule{ident} \texttt{"("} \rule{atom} \texttt{","} \rule{var} \texttt{")"};\\
        \rule{abstractaction} \> = \> \rule{atom};\\
        \rule{test} \> = \> \texttt{"B("} \rule{belquery} \texttt{")"}\\
            \>$\mid$\> \texttt{"G("} \rule{goalquery} \texttt{")"}\\
            \>$\mid$\> \rule{test} \texttt{"\&"} \rule{test}\\
            \>$\mid$\> \texttt{"("} \rule{test} \texttt{")"};\\
        \rule{adoptgoal} \> = \> \texttt{"adopta("} \rule{goalvar} \texttt{")"}\\
            \>$\mid$\> \texttt{"adoptz("} \rule{goalvar} \texttt{")"};\\
        \rule{dropgoal} \> = \> \texttt{"dropgoal("} \rule{goalvar} \texttt{")"}\\
            \>$\mid$\> \texttt{"dropsubgoals("} \rule{goalvar} \texttt{")"}\\
            \>$\mid$\> \texttt{"dropsupergoals("} \rule{goalvar} \texttt{")"};\\
        \rule{createaction} \> = \> \texttt{"create("} \rule{ident} \texttt{","} \rule{ident} \texttt{")"};\\
        \rule{releaseaction} \> = \> \texttt{"release("} \rule{ident} \texttt{")"};\\
        \rule{moduleaction} \> = \> \rule{ident} \texttt{"."} \rule{maction};\\
        \rule{maction}  \> = \> \texttt{"execute("} \rule{test} \texttt{")"}\\
            \>$\mid$\> \texttt{"updateBB("} \rule{literal} \texttt{")"}\\
            \>$\mid$\> \rule{adoptgoal}\\
            \>$\mid$\> \rule{dropgoal}\\
            \>$\mid$\> \texttt{"B("} \rule{literal} \texttt{")"}\\
            \>$\mid$\> \texttt{"G("} \rule{literal} \texttt{")"};\\
        \rule{sequenceplan} \> = \> \rule{plan} \texttt{";"} \rule{plan};\\
        \rule{ifplan} \> = \> \texttt{"if"} \rule{test} \texttt{"then"} \rule{scopeplan} [\texttt{"else"} \rule{scopeplan}];\\
        \rule{whileplan} \> = \> \texttt{"while"} \rule{test} \texttt{"do"} \rule{scopeplan};\\
        \rule{atomicplan} \> = \> \texttt{"["} \rule{plan} \texttt{"]"};\\
        \rule{scopeplan} \> = \> \texttt{"\{"} \rule{plan} \texttt{"\}"};\\
        \rule{pgrules} \> = \> \rule{pgrule}+;\\
        \rule{pgrule} \> = \> [\rule{goalquery}] \texttt{"$<$-"} \rule{belquery} \texttt{"$\mid$"} \rule{plan};\\
        \rule{pcrules} \> = \> \rule{pcrule}+;\\
        \rule{pgrule} \> = \> \rule{atom} \texttt{"$<$-"} \rule{belquery} \texttt{"$\mid$"} \rule{plan};\\
        \rule{prrules} \> = \> \rule{prrule}+;\\
        \rule{prrule} \> = \> \rule{planvar} \texttt{"$<$-"} \rule{belquery} \texttt{"$\mid$"} \rule{planvar};\\
        \rule{goalvar} \> = \> \rule{atom} \{\texttt{"and"} \rule{atom}\};\\
        \rule{planvar} \> = \> \rule{plan}\\
            \>$\mid$\> \rule{var}\\
            \>$\mid$\> \texttt{"if"} \rule{test} \texttt{"then"} \rule{scopeplanvar} [\texttt{"else"} \rule{scopeplanvar}]\\
            \>$\mid$\> \texttt{"while"} \rule{test} \texttt{"do"} \rule{scopeplanvar}\\
            \>$\mid$\> \rule{planvar} \texttt{";"} \rule{planvar};\\
        \rule{scopeplanvar} \> = \> \texttt{"\{"} \rule{planvar} \texttt{"\}"};\\
        \rule{literals} \> = \> \rule{literal} \{\texttt{","} \rule{literal}\};\\
        \rule{literal} \> = \> \rule{atom}\\
            \>$\mid$\> \rule{infixatom}\\
            \>$\mid$\> \texttt{"not"} \rule{atom}\\
            \>$\mid$\> \texttt{"not"} \rule{infixatom};\\
        \rule{belquery} \> = \> \texttt{"true"}\\
            \>$\mid$\> \rule{belquery} \texttt{"and"} \rule{belquery}\\
            \>$\mid$\> \rule{belquery} \texttt{"or"} \rule{belquery}\\
            \>$\mid$\> \texttt{"("} \rule{belquery} \texttt{")"}\\
            \>$\mid$\> \rule{literal};\\
        \rule{goalquery} \> = \> \texttt{"true"}\\
            \>$\mid$\> \rule{goalquery} \texttt{"and"} \rule{goalquery}\\
            \>$\mid$\> \rule{goalquery} \texttt{"or"} \rule{goalquery}\\
            \>$\mid$\> \texttt{"("} \rule{goalquery} \texttt{")"}\\
            \>$\mid$\> \rule{atom};\\
        \rule{iv} \> = \> \rule{ident} $\mid$ \rule{var};\\
        \rule{groundatom} \> = \> \rule{ident} \texttt{"("} \rule{groundpars} \texttt{")"};\\
        \rule{groundpars} \> = \> \rule{groundpar} \{\texttt{","} \rule{groundpar}\};\\
        \rule{groundpar} \> = \> \rule{ident} $\mid$ \rule{num} $\mid$ \texttt{"\_"} $\mid$ \rule{atom}\\
            \>$\mid$\> \texttt{"["} [\rule{groundpars}] \texttt{"]"}\\
            \>$\mid$\> \texttt{"["} \rule{groundpars} \texttt{"$\mid$"} \rule{var} \texttt{"]"};\\
        \rule{upperatom} \> = \> \rule{var} \texttt{"("} [\rule{pars}] \texttt{")"};\\
        \rule{atom} \> = \> \rule{ident} \texttt{"("} [\rule{pars}] \texttt{")"};\\
        \rule{infixatom} \> = \> \rule{par} (\texttt{"="} $\mid$ \texttt{"$>$"} $\mid$ \texttt{"$<$"} $\mid$ \texttt{"$<$="} $\mid$ \texttt{"$>$="}  $\mid$ \texttt{"=$>$"} $\mid$ \texttt{"=$<$"}) \rule{par};\\
        \rule{pars} \> = \> \rule{par} \{\texttt{","} \rule{par}\};\\
        \rule{par} \> = \> \rule{var} $\mid$ \rule{num} $\mid$ \texttt{"\_"} $\mid$ \rule{atom}\\
            \>$\mid$\> \rule{par}(\texttt{"+"} $\mid$ \texttt{"-"} $\mid$ \texttt{"*"} $\mid$ \texttt{"/"}) \rule{par}\\
            \>$\mid$\> \texttt{"["} [\rule{pars}] \texttt{"]"}\\
            \>$\mid$\> \texttt{"["} (\rule{artexps} $\mid$ \rule{pars}) \texttt{"$\mid$"} \rule{var} \texttt{"]"};\\
        \rule{artexps} \> = \> \rule{artexp} \{\texttt{","} \rule{artexp}\};\\
        \rule{artexp} \> = \> \rule{var} $\mid$ \rule{num}\\
            \>$\mid$\> \rule{artexp}(\texttt{"+"} $\mid$ \texttt{"-"} $\mid$ \texttt{"*"} $\mid$ \texttt{"/"}) \rule{artexp}\\
            \>$\mid$\> \texttt{"("} \rule{artexp} \texttt{")"};\\
        \rule{var} \> = \> \texttt{"A"}..\texttt{"Z"} \{\texttt{"a"}..\texttt{"z"} $\mid$ \texttt{"A"}..\texttt{"Z"} $\mid$ \texttt{"0"}..\texttt{"9"} $\mid$ \texttt{"\_"}\};\\
        \rule{ident} \> = \> \texttt{"a"}..\texttt{"z"} \{\texttt{"a"}..\texttt{"z"} $\mid$ \texttt{"A"}..\texttt{"Z"} $\mid$ \texttt{"0"}..\texttt{"9"} $\mid$ \texttt{"\_"\}};\\
        \rule{num} \> = \> (\texttt{"0"}..\texttt{"9"})+;\\
        \end{tabbing}



An individual 2APL agent may be composed of various ingredients that
specify different aspects of the agency. A 2APL agent can be
programmed by implementing the initial state of those ingredients.
The state of some of these ingredients will change during the
agent's execution while the state of other ingredients remains the
same during the execution of the agent. In the rest of this section,
we will discuss each ingredient and give examples to illustrate
them.

\begin{section}{Beliefs and goals}

A 2APL agent may have beliefs and goals which change during the
agent's execution. The \emph{beliefs} of an agent is implemented in
its belief base and contains information about its surrounding world
including other agents. The implementation of the initial belief
base starts with the keyword '{\tt Beliefs:}' followed by one or
more belief expressions of the form \bla{belief}. Note that a
\bla{belief} expression is treated as a Prolog fact or rule such
that the belief base of a 2APL agent becomes a Prolog program. One
can use arbitrary Prolog programs to represent an agent's belief
base, but this should be done with care as dynamics constructs of
Prolog such as assert and retract may interact with belief update
actions, resulting in undesirable behavior. All facts are assumed to
be grounded. The code fragment below illustrates the implementation
of the initial belief base of {\tt harry} which represents his
information about its {\tt blockworld} environment. In particular,
{\tt harry} believes that it starts working at location $(0,1)$, and
that the {\tt blockworld} environment is clean if there are no bombs
anymore and the agent is not carrying a bomb.

\begin{verbatim}
Beliefs:
  start(0,1).
  clean( blockworld ) :- not bomb(X,Y) , not carry(bomb).
\end{verbatim}

The \emph{goals} of a 2APL agent are implemented by its goal base,
which consists of formulas each of which denotes a situation the
agent wants to realize (not necessary all at once). The
implementation of the initial goal base starts with the keyword
'{\tt Goals:}' followed by a list of goal expressions of the form
\bla{goal}. Each goal expression is a conjunction of ground atoms.
Note that the separated goals in the goal base are separated by a
comma. Ground atoms are treated as Prolog facts. Note that having a
single conjunctive goal, say '{\tt a and b}', is different than
having two separate goals '{\tt a , b}'. In the latter case, the
agent wants to achieve two desirable situations independently of
each other. The code fragment below is the implementation of the
initial goal base of {\tt harry} which indicates that he wants to
achieve a desirable situation in which the {\tt blockworld} is
clean.

\begin{verbatim}
Goals:
  clean( blockworld )
\end{verbatim}

The beliefs and goals of agents are related to each other. In fact,
if an agent believes a certain fact, then the agent should not
pursue that fact as a goal. This means that if an agent modifies its
belief base, then its goal base may be modified as well.
\end{section}


\begin{section}{Basic actions}

In order to achieve its goals, a 2APL agent needs to act. Basic
actions specify the capabilities that an agent has to achieve its
desirable situation. The basic actions will constitute an agent's
plan, as we will see in the next subsection. In 2APL, six types of
basic actions are distinguished: actions to update the belief base,
communication actions, external actions to be performed in an
agent's environment, abstract actions, actions to test the belief
and goal bases, and actions to manage the dynamics of goals.

\begin{subsection}*{Belief Update Action}

A {\em belief update action} updates the belief base of an agent
when executed. A belief update action \bla{beliefupdate} is an
expression of the predicate argument form, where the predicate
starts with a capital letter. Such an action is specified in terms
of pre- and post-conditions. An agent can execute a belief update
action if the pre-condition of the action is derivable from its
belief base. The pre-condition is a formula consisting of literals
composed by disjunction and conjunction operators. The execution of
a belief update action modifies the belief base in such a way that
after the execution the post-condition of the action is derivable
from the belief base. The post-condition of a belief update action
is a list of literals. The update of the belief base by such an
action removes the atom of the negative literals from the belief
base and adds the positive literals to the belief base. The
specification of the belief update actions starts with the keyword
'{\tt BeliefUpdates:}' followed by the specifications of a set of
belief update actions \bla{beliefupdatespecification}.

The code fragment below shows an example of the specification of the
belief update actions of {\tt harry}. In this example, the
specification of the {\tt PickUp()} action indicates that this
belief update action can be performed if the agent does not already
carry a bomb (i.e., the agent can carry only one bomb) and that
after performing this action the agent will carry a bomb.  Note that
the agent cannot perform two {\tt PickUp()} action consecutively.
Note the use of variables in the specification of {\tt
RemoveBomb(X,Y)}; it requires that an agent can remove a bomb if it
is the same location as the bomb. Note also that variables in the
post-conditions are bounded since otherwise the facts in the belief
base will not be grounded.

\begin{verbatim}
BeliefUpdates:
  { bomb(X,Y) }         RemoveBomb(X,Y)     { not bomb(X,Y) }
  { true }              AddBomb(X,Y)        { bomb(X,Y) }
  { carry( bomb ) }     Drop( )             { not carry( bomb ) }
  { not carry( bomb ) } PickUp( )           { carry( bomb ) }
\end{verbatim}

\end{subsection}

\begin{subsection}*{Communication Action}

A \emph{communication action} passes a message to another agent. A
communication action \bla{sendaction} can have either three or five
parameters. In the last case, the communication action is the
expression {\tt send(Receiver, Performative, Language, Ontology,
Content)} where {\tt Receiver} is a name referring to the receiving
agent, {\tt Performative} is a speech act name (e.g. inform,
request, etc.), {\tt Language} is the name of the language used to
represent the content of the message, {\tt Ontology} is the name of
the ontology used in the content of the message, and {\tt Content}
is an expression representing the content of the message. It is
often the case that agents assume a certain language and ontology
such that it is not necessary to pass them as parameters of their
communication actions. The second version of the communication
action is therefore the expression {\tt send(Receiver, Performative,
Content)}. It should be noted that the 2APL interpreter is built on
the JADE platform. For this reason, the name of the receiving agent
can be a local name or a full JADE name. A full jade name has the
form {\tt localname@host:port/JADE} where {\tt localname} is the
name as used by 2APL, {\tt host} is the name of the host running the
agent's container and {\tt port} is the port number where the
agent's container, should listen to (see \cite{jade2005} for more
information on JADE standards). The following is an example of a
communication action by which {\tt sally} informs {\tt harry} about
a bomb location.

\begin{verbatim}
send( harry, inform, La, On, bombAt( X1, Y1 ) )
\end{verbatim}

\end{subsection}


\begin{subsection}*{External Action}\label{sec:externalaction}

An \emph{external action} is supposed to change the external
environment in which the agents operate. The effects of external
actions are assumed to be determined by the environment and might
not be known to the agents beforehand. The agent thus decides to
perform an external action and the external environment determines
the effect of the action. The agent can come to know the effects of
an external action by performing a sense action, defined as an
external action, or by means of events generated by the environment.
An external action \bla{externalaction} is an expression of the form
{\tt @Env(Action,ReturnVal)}. The parameter {\tt Env} is the name of
the agent's environment as specified in the MAS-file and {\tt
Action} is the action the agent wants to perform in the environment.
The parameter {\tt ReturnVal} is a list of values, possibly an empty
list, returned by the corresponding method. An example of the
implementation of an external action is {\tt @blockworld( enter( X,
Y, blue ), \_ )}. This action causes an agent to enter the
blockworld environment at position {\tt (X,Y)}. The appearance color
of the agent will be blue. The execution of this action causes the
agent to appear in blue at position {\tt (X,Y)} in the blockworld
environment. An empty list is returned.
\end{subsection}

\begin{subsection}*{Abstract Action}

An \emph{abstract action} is an abstraction mechanism allowing the
encapsulation of a plan by a single action. An abstract action will
be instantiated with a concrete plan when the action is executed.
The instantiation of a plan with an abstract action is specified
through special rules called PC-rule, which stands for procedure
rules (see section \ref{sec:pcrules} for a description of PC-rules).
In fact, the general idea of an abstract action is similar to a
procedure in imperative programming languages while the PC-rules
function as procedure definitions. Like a procedure call, an
abstract action \bla{abstractaction} is an expression of the
predicate argument form starting with a lowercase letter.
\end{subsection}

\begin{subsection}*{Belief and Goal Test Actions}

A \emph{belief test action} is to test whether a belief expression
is derivable from an agent's belief base, i.e., it tests whether the
agent has a certain belief. A belief test action \bla{testbelief} is
an expression of the predicate argument form followed by a question
mark. Such a test may generate a substitution for the variables that
are used as arguments in the belief expression. A belief test action
is basically a (Prolog) query to the belief base which can be used
in a plan to 1) instantiate a variable in rest of the plan, or 2)
block the execution of the plan (if the test fails). For example,
let the belief base of {\tt harry} contains the fact {\tt
start(0,1)}. The belief test action {\tt B(start(X,Y))} succeeds
resulting in the substitution {\tt [X/0 , Y/1]}. If there are more
than one substitutions possible, then the substitution that is
resulted from unifying the query term with the first term in the
belief base is taken.

A \emph{goal test action} is to test whether a formula is derivable
from the goal base, i.e., whether the agent has a certain goal from
which the formula is derivable. A goal test action \bla{testgoal} is
an expression of the predicate argument form followed by an
exclamation mark. For example, if an agent has a goal {\tt p(a) and
q(b)}, then the goal test action {\tt G(p(X))} succeeds resulting in
the substitution {\tt [X/a]}. Like a belief test action, this action
can be used to instantiate a variable with a value, or to block the
execution of the rest of a plan.

The belief and goal test actions can be combined forming complex
test actions. For example, {\tt B(start(X,Y)) \& G(pos(V,W))} tests
the agent's start and desired positions.
\end{subsection}

\begin{subsection}*{Goal Dynamics Actions}\label{sec:goaldyn}

The \emph{adopt goal} and \emph{drop goal} actions are used to adopt
and drop a goal to and from the agent's goal base, respectively. The
adopt goal action \bla{adoptgoal} can have two different forms: {\tt
adopta($\phi$)} and {\tt adoptz($\phi$)}. These two actions can be
used to add the goal $\phi$ (a conjunction of literals) to the begin
and to the end of an agent's goal base, respectively. Note that the
programmer has to ensure that the variables in $\phi$ are
instantiated before these actions are executed since the goal base
should always be grounded. Finally, the drop goal action
\bla{dropgoal} can have three different forms: {\tt
dropgoal($\phi$)}, {\tt dropsubgoals($\phi$)}, and {\tt
dropsupergoals($\phi$)}. These actions can be used to drop from an
agent's goal base, respectively, exactly the goal $\phi$, all goals
that are subgoals of $\phi$, and all goals that have $\phi$ as a
subgoal. For example, let an agent have the goal {\tt p(a) and
q(b)}. Then, the action {\tt dropgoal(p(a))} or {\tt dropgoal(p(a)
and q(b) and r(c))} will not remove the goal {\tt p(a) and q(b)}
from the goal base, but the action {\tt dropgoal(p(a) and q(b))}
does remove the goal. Also, the actions {\tt dropsubgoal(p(a) and
q(b) and r(c)))} {\tt dropsupergoal(p(a)} will remove the goal {\tt
p(a) and q(b)} from the goal base.
\end{subsection}
\end{section}


\begin{section}{Plans}

In order to reach its goals, a 2APL agent adopts \emph{plans}. A
plan consists of basic actions composed by process operators. In
particular, basic actions can be composed by means of the sequence
operator, conditional choice operators, conditional iteration
operator, and an unary operator to identify (region of) plans that
should be executed atomically, i.e., the actions should not be
interleaved with the actions of other plans of the agent.

The sequence operator {\tt ;} is a binary operator generating the
plan \bla{sequenceplan} from two other plans, e.g., {\tt goto( X, Y
); @blockworld( pickup( ), \_ )} is a sequence plan consisting of an
abstract action followed by an external action. A sequence plan
${\tt \pi_1;\pi_2}$ indicates that the first plan $\pi_1$ should be
performed before the second plan $\pi_2$.

The conditional choice operator generates the plan \bla{ifplan},
which is an expression of the form {\tt if $\phi$ then $\pi_1$ else
$\pi_2$}. The following is an example of such a plan:

\begin{verbatim}
if B(A > X) then
{   @blockworld( west(), L );
    goto( X, Y )
}
else if B(A < X) then
{   @blockworld( east(), L );
    goto( X, Y )
}
\end{verbatim}

The condition of such an expression (i.e., $\phi$) is evaluated with
respect to an agent's belief base possibly resulting a substitution.
The scope of application of the substitution is limited to the body
of this \bla{ifplan} expression. This expression can thus be
interpreted as to perform the if-part of the plan (i.e., $\pi_1$)
when the agent believes $\phi$, otherwise the agent performs the
else-part of the plan (i.e., $\pi_2$).

The conditional iteration operator generates the plan
\bla{whileplan} which is an expression of the form {\tt while $\phi$
do $\pi$}. The condition $\phi$ should also be evaluated with
respect to an agent's belief base. Like the conditional choice
operator, the scope of application for a possible substitution is
limited to the body of this \bla{whileplan} expression. This
iteration expression is then interpreted as to perform the plan
$\pi$ in the body of the while loop as long as the agent believes
$\phi$.

The last unary operator generates the plan
\bla{atomicplan} which is an expression of the form {\tt [$\pi$]}.
This plan is interpreted as an atomic plan, which should be executed
at once (atomically) ensuring that the execution of $\pi$ is not
interleaved with the execution of the actions of other plans of the
same agent. Note that an agent can have different plans at the same
time.

The initial plans of a 2APL agent are implemented by its plan base.
The implementation of the initial plan base starts with the keyword
'{\tt Plans:}' followed by a list of plans (plans are separated by
comma). The following code fragment illustrates the implementation
of the initial plan base of {\tt harry}, which first tests where he
believes to enter, then associate a robot body to get an appearance
in the environment, and finally enters the {\tt blockworld} at the
believed position. The exact meaning of the external actions that
could be performed in the {\tt blockworld} is explained in chapter
\ref{chap:environment}. As explained in the next section, during
execution of the agent, the plan base will be filled with plans by
means of reasoning rules.

\begin{verbatim}
Plans:
    B(start(X, Y));
    @blockworld(associateWith(robot0),_,0);
    @blockworld(enter(X, Y, blue),_,0)
\end{verbatim}

\end{section}



\begin{section}{Reasoning rules}

The 2APL programming language provides constructs to implement
practical reasoning rules that can be used to implement the
generation of plans. In particular, three types of practical
reasoning rules are proposed: planning goal rules, procedural rules,
and plan repair rules. In the following subsections, we explain
these three types of rules.

\begin{subsection}*{Planning Goal Rules (PG rules)}\label{sec:pgrules}

A planning goal rule can specifies that an agent should generate a
plan if it has certain goals and beliefs. The specification of a
planning goal rule \bla{pgrule} consists of three entries: the head
of the rule, the condition of the rule, and the body of the rule.
The head and the condition of a planning goal rule are query
expressions used to test if the agent has a certain goal and belief,
respectively. The body of the rule is a plan in which variables may
occur. These variables can be bound by the variables that occur in
the goal and belief expressions. A planning goal rule of an agent
can be applied when the goal and belief expressions (in the head and
the condition of the rule) are derivable from the agent's goal and
the belief bases, respectively.  The application of a planning goal
rule involves an instantiation of variables that occur in the head
and condition of the rule as they are queried from the goal and
belief bases. The resulted substitution will be applied to the
generated plan to instantiate its variables. The planning goal rules
are preceded by the keyword {\tt PG-rules:} and have the following
form:

\bla{query}? "$<-$" \bla{query} "$|$" \bla{plan}

Note that the head of the rule is optional which means that the
agent can generate a plan only based on its belief condition. The
code fragment below is an example of a planning goal rule of {\tt
harry} indicating that a plan to achieve the goal {\tt
clean(blockworld)} can be generated if the agent believes there is a
bomb at position {\tt (X,Y)}. Note that {\tt goto(X,Y)} is an
abstract action the execution of which replaces a plan for going to
position {\tt (X,Y)}. After performing this plan, {\tt harry}
performs a pickup action in the blockworld, modifying his beliefs
such that he now believes he carries a bomb, modifying his beliefs
that there was a bomb at {\tt (X,Y)}, going to position {\tt (0,0)},
where the bomb should be dropped in a dustbin, perform the drop
action in the blockworld, and finally modifying his beliefs that he
does not carry a bomb anymore.

\begin{verbatim}
PG-rules:

clean( blockworld ) <- bomb( X, Y ) |
    {
        goto( X, Y );
        @blockworld( pickup( ), _ );
        PickUp( );
        RemoveBomb( X, Y );
        goto( 0, 0 );
        @blockworld( drop( ), _ );
        Drop( )
    }
\end{verbatim}
\end{subsection}

\begin{subsection}*{Procedural Rules (PC rules)}\label{sec:pcrules}

Procedural rules generate plans as a response to 1) the reception of
messages sent by other agents, 2) events generated by the external
environment, and 3) the execution of abstract actions. Like planning
goal rules, the specification of procedural rules consist of three
entries.  The only difference is that the head of the procedural
rules is an atom \bla{atom} (predicate-argument expression), rather
than a query \bla{query}, which represents either a message, an
event, or an abstract action. A message and an event are represented
by atoms with the special predicates {\tt message} and {\tt event},
respectively. An abstract action is represented by any predicate
name starting with a lowercase letter. Note that like planning goal
rules, a procedural rule has a belief condition indicating when a
message (or received event or abstract action) should cause the
generation of a plan. Thus, a procedural rule can be applied if the
agent has received a message (or an event or if the agent executes
an abstract action) and the belief query of the rule is derivable
from its belief base. The instantiation of variables and the
application of the resulting substitutions to the plan variables are
the same as with planning goal rules. The procedural rules are
preceded by the keyword {\tt PC-rules:} and have the following form:

                \bla{atom} "$<-$" \bla{query} "$|$" \bla{plan}

The code fragment below shows an example of procedural call rules
that is used for implementing {\tt harry}. This rule indicates that
if {\tt harry} receives a message from {\tt sally} informing him
that there is a bomb at position {\tt (X,Y)}, then his beliefs will
be updates with this new fact and goal to clean the {\tt blockworld}
is adopted, if he does not believe that there is already a bomb at a
position {\tt (A,B)}. Otherwise, he updates his beliefs with the the
received information without adopting the goal. This is because {\tt
harry} is assumed to this goal as long as he believes there is a
bomb somewhere.

\begin{verbatim}
PC-rules:

message( sally, inform, La, On, bombAt( X, Y ) ) <- true |
    {
      if B( not bomb( A, B ) ) then
        { AddBomb( X, Y );
          adoptz( clean( blockworld ) )
        }
      else
        { AddBomb( X, Y )
        }
    }
\end{verbatim}

Another example of a procedural rule is illustrated below. This rule
is used by {\tt harry} by including the file {\tt person.2apl} (see
section~\ref{sec:include} about include files). This rule indicates
that the execution of the abstract action {\tt goto(X,Y)} causes
this action to be replaced with the plan from the body of the rule.
This plan implements a movement toward position {\tt (X,Y)} by
moving one square at a time. Note the use of recursion in this
PC-rule.

\begin{verbatim}
PC-rules:

goto( X, Y ) <- true |
    {
        @blockworld( sensePosition(), POS );
        B(POS = [actionresult([A,B])]);
        if B(A > X) then
            {   @blockworld( west(), L );
                goto( X, Y )
            }
        else if B(A < X) then
            {   @blockworld( east(), L );
                goto( X, Y )
            }
        else if B(B > Y) then
            {   @blockworld( north(), L );
                goto( X, Y )
            }
        else if B(B < Y) then
            {   @blockworld( south(), L );
                goto( X, Y )
            }
    }
\end{verbatim}
\end{subsection}


\begin{subsection}*{Plan Repair Rules (PR rules)}\label{sec:prrules}

The execution of an agent's plan fails if the execution of the first
action of the plan fails. To repair such a plan, 2APL provides
so-called plan repair rules. Like other practical reasoning rules, a
plan repair rule consists of three entries: two abstract plans and
one belief query expression. We have used the term abstract plan
since such plans include a variable that can be instantiated with a
plan. A plan repair rule starts with an action (the execution of
which is failed) followed by a plan variable. A plan repair rule
indicates that if the execution of the first action of the agent's
plan fails and the agent has a certain belief, then the failed plan
should be replaced by another plan. The plan repair rules are
preceded by the keyword {\tt PR-rules:} and have the following form:

        \bla{planvar} "$<-$" \bla{query} "$|$" \bla{planvar}

A plan repair rule of an agent can thus be applied if:
\begin{enumerate}
    \item the execution of one of its plan fails,
    \item the failed plan can be matched with the abstract plan in the head of the rule, and
    \item the belief query expression is derivable from the agent's belief base.
\end{enumerate}

The satisfaction of these three conditions results in a substitution
that binds the variable that occur in the abstract plan in the body
of the rule. Note that one of these variables is a plan variable
which will be instantiated with the the plan without its first
action. The resulted substitutions will be applied to the second
abstract plan (the body of the rule) resulting a new (repaired)
plan. The code fragment below shows an example of a plan repair rule
of {\tt harry}. This rule is used for the situation in which the
execution of a plan that starts with the external action {\tt
@blockworld( pickup(), \_ );} fails. Such an action fails in case
there is no bomb to be picked up (e.g., when it is removed by
another agent). The rule states that the plan should be replaced by
another plan consisting of an external action to sense its current
position after which it removes the bomb from its current position.
Note that in this case the rest of the original plan denoted by {\tt
REST} is dropped, as it is not used anymore within the rule.

\begin{verbatim}
PR-rules:

@blockworld( pickup(), _ ); REST <- true |
    {
        @blockworld( sensePosition(), POS );
        B(POS = [actionresult([X,Y])]);
        RemoveBomb( X, Y )
    }
\end{verbatim}

The execution of a plan fails if the execution of its first action
fails.  When the execution of an action fails depends on the type of
action. The execution of: (1) a belief update action fails if the
action is not specified, (2) an abstract action if there is no
applicable procedural rule, (3) an external (Java) action if the
environment succeeds, possibly after retrying within the specified
time-out limit, (4) a belief test action if the belief expression is
not derivable from the belief base, (5) a test goal action if the
goal expression is not derivable from the goal base, and (6) an
atomic plan section if one of its actions fails. The execution of
all other actions will always be successful. When the execution of
an action fails, then the execution of the whole plan is stopped.
The failed action will not be removed from the failed plan such that
it can be repaired by a PR-rule.

\end{subsection}
\end{section}


\begin{section}{The deliberation cycle}

The beliefs, goals, plans and reasoning rules form the mental states
of the 2APL agent. What the agent should do with these mental
attitudes is defined by means of the deliberation cycle. The
deliberation cycle states which step the agent should perform next,
e.g. execute an action or apply a reasoning rule. The deliberation
cycle can thus be viewed as the interpreter of the agent program, as
it determines which deliberation steps should be performed in which
order. 2APL provides the deliberation cycle as illustrated in figure
\ref{fig:delib}. The 2APL deliberation cycle can be changed by
editing and recompiling the codes of the 2APL interpreter. However,
we plan to extend the platform such that the deliberation cycle can
be modified through parameters.

\begin{figure}[ht]
    \centering{\epsfig{figure=images/deliberation.eps,width=0.8\textwidth,angle=0}}
    \caption{The deliberation cycle of a 2APL agent.}\label{fig:delib}
\end{figure}

\end{section}


\begin{section}{Including files}\label{sec:include}

In a multi agent system it can happen that there are more instances
of one agent type. Although these agents are almost the same, they
might have slightly different beliefs, goals, plans or rules. 2APL
introduces an encapsulation mechanism to include agent files into
other agent files. One can include another file with the {\tt
Include: filename} command. The resulting agent will be a union of
the two (or more) files. In our example, for instance, both {\tt
harry} and {\tt sally} are capable of moving to a certain location
in the {\tt blockworld}. That is to say, they have the same PC-rule
{\tt goto(X,Y)}. This rule is specified in a file {\tt person.2apl}
which is included by both {\tt harry} and {\tt sally}. An included
file can also include files. This makes it possible to specify
specific information shared by agents in a separate file that can be
included by all agents with that role.
\end{section}


\begin{section}{Modules in 2APL}

Modularity is an essential principle in structured programming in
general and in agent programming in particular. In 2APL
modularization is considered as a mechanism to structure an
individual agent's program in separate modules. Each module
encapsulates cognitive components such as beliefs, goals, plans, and
reasoning rules. In practice, a 2APL module is used to specify a
specific functionality that can be used to handle specific
situations or tasks. In programming terminology, a 2APL module is a
(cognitive) data structure specifying an agent's (cognitive) state.
The execution of an individual 2APL agent program, which is supposed
to modify the state of the agent program, is then realized by the
deliberation process, as explained in previous section.

A 2APL multi-agent program consists of a set of module
specifications each with a unique name. Initially, a subset of these
module specifications is identified as specifying the initial state
of individual agents. The execution of a multi-agent program is then
the instantiation of this subset of module specifications followed
by performing a deliberation process on each module instance. In
this way, an instance of a module specification forms the initial
state of an individual agent. It should be emphasized that a module
instance specifies the cognitive state of an agent while the agent
itself is the deliberation process working on the cognitive state.
It is important to notice that this module version of 2APL is
perfectly in line with the non-module version of 2APL if one uses
one module specification per agent, i.e., each agent is initially
specified by one module specification (i.e., file with .2apl
extension) and no additional modules is created at run-time.

When using modules in 2APL, a programmer can perform a wide range of
operations on modules. These module-related operations enable a
programmer to directly and explicitly control \textit{when} and
\textit{how} modules are used. 2APL provides a set of programming
constructs that can be used by an agent programmer to perform module
operations. Module in 2APL can be used to implement a variety of
agent concepts such as agent role and agent profile. In fact, a
module can be used as a mechanism to specify a role that can be
enacted by an agent during its execution. Modules can also be used
to implement agents that can represent and reason about other
agents.

\begin{subsection}{Operations on Modules}
In the following subsections, we explain 2APL operations that can be
performed on modules.

\begin{subsubsection}{Creating and Releasing Module Instances}
The first module-related action is \ttt create(s,m) \ttt, which can
be used to create an instance of the module specification named \ttt
s \ttt. The name that is assigned to the created module instance is
given by the second argument \ttt m \ttt. The creating module
instance (also called the owner of the created module instance or
simply the owner) can use this name to perform further operations on
the created module instance (also called the owned module instance).
One module specification can be instantiated more than once by one
or more module instances. In such a case, the creating module
instance should assign a unique name to each created module
instance. A module instance with identifier {\tt m} can be released
by its owner by means of the \ttt{release(m)} action. The released
module instance \ttt{m} will be removed/lost.
\end{subsubsection}


\begin{subsubsection}{Executing Module Instances}
A module instance \ttt{m} can be executed by its owner through the
\ttt execute(m,t) \ttt action. The execution of a module instance,
performed by its owner, has two effects: 1) it suspends the
execution of the owner module instance, and 2) it starts the
execution of the owned module instance. The execution of the owner
module instance will be resumed as soon as the execution of the
owned module instance is terminated. In a sense, an agent that
executes an owned module instance, stops deliberating on its current
cognitive state and starts deliberating on a new cognitive state.
The termination of the owned module instance is based on the
mandatory condition \ttt t \ttt (i.e., the second argument of the
execute action). This condition is of the form \rule{test} and
consists of beliefs and goal tests performed on the beliefs and
goals of the owned module instance. As soon as this condition holds,
the execution of the owned module instance terminates and the
execution control is given back to the owner module instance. This
test is performed at each deliberation cycle, i.e., at each
deliberation cycle performed on the owned module instance it is
checked if the module instance satisfies the condition. Note that
the owner cannot force the owned module instance's execution to stop
because its own execution has been suspended.
\end{subsubsection}

\begin{subsubsection}{Testing and Updating Module Instances}
The owner of a module instance can query and update the internals of
the instance. In particular, the owner can test/query whether
certain beliefs and goals are entailed by the beliefs and goals of
its owned module instance {\tt m} through actions
\(\ttt{m.B(}\varphi\ttt)\) and \(\ttt{m.G(}\varphi\ttt)\), where
$\varphi$ is a literal. Also, the beliefs of a module instance
\ttt{m} can be updated by means of the action
\(\ttt{m.updateBB(}\varphi\ttt)\), where \(\varphi\) is a literal.
Finally, goals can be added and removed from the goals of a module
instance \ttt{m} by means of the action \ttt m.\rule{adoptgoal}\ttt
and \ttt m.\rule{dropgoal}\ttt, respectively.
\end{subsubsection}

\begin{figure}[ht]
    \begin{center}
        \epsfig{figure=images/modules.eps,width=.4\textwidth}
    \end{center}
    \caption{A typical life cycle of a module.}\label{fig:execution}
\end{figure}

A typical life cycle of a module in terms of these operations is
illustrated in Figure~\ref{fig:execution}, which proceeds as
follows.  A module instance \(A\) can create a new module instance
\(B\) from a specification file. The module instance \(A\) can
modify \(B\)'s internal state using update actions. In this case,
\(A\) updates the beliefs of \(B\) with literal \ttt bel \ttt. The
module instance \(A\) can transfer the execution control to the
module instance \(B\) by the execute action. The execution of \(B\)
continues until the state \(B\) satisfies the stopping condition
\ttt stop \ttt. The execution control is then returned back to the
module instance \(A\). When \(A\) is active again, it can query
\(B\)'s internal state by the testing its beliefs or goals and
release (remove) it.
\end{subsection}


\begin{subsection}{An Example of a Modular 2APL Multi-Agent Program}
The following example is provided to illustrate the idea of
module-related constructs and their use to implement an agent's
role. Suppose we need to build a multi-agent system in which one
single manager and three workers cooperate to collect bombs in an
environment called gridworld. The manager coordinates the activities
of the three workers by asking them either to play the explorer role
to detect the bombs in the gridworld environment or to play the
carrier role to carry the detected bombs to a safe depot and store
them.

For this example, which can be implemented as the multi-agent
program illustrated in Figure \ref{fig:mas}, the manager module
(i.e., \texttt{manager.2apl}) specifies the initial state of the
manager agent with the name \texttt{m} (the implementation of the
manager module is presented in Figure \ref{fig:managercode}). Note
that only one manager agent will be initialized and created (line
\ref{code:man}). Moreover, the worker module (\texttt{worker.2apl};
see Figure \ref{fig:workercode}) specifies the initial state of
three worker agents. The names of the worker agents in the
implemented multi-agent system are \texttt{w1}, \texttt{w2}, and
\texttt{w3} (lines \ref{code:wor1} tot \ref{code:wor3}). As we will
see later in this section, the explorer and carrier roles will be
played by the worker agents at runtime.

\begin{figure}[H]
\begin{Verbatim}[frame=single,numbers=left,numbersep=2pt,commandchars=\\\[\]]
<apaplmas>
  <environment name="blockworld" file="blockworld.jar">
    <parameter key="gridWidth" value="18"/>
    <parameter key="gridHeight" value="18"/>
  </environment>

  <agent name="m" file="manager.2apl"/> \label[code:man]
  <agent name="w1" file="worker.2apl"/> \label[code:wor1]
  <agent name="w2" file="worker.2apl"/>
  <agent name="w3" file="worker.2apl"/> \label[code:wor3]
</apaplmas>
\end{Verbatim}
\caption{The multi-agent program of the running
example.}\label{fig:mas}
\end{figure}

The manager module can be implemented as in Figure
\ref{fig:managercode}. The belief updates, beliefs, goals, and
reasoning rules should be read as before. The two PG-rules (lines
\ref{code:man:pgrule1} and \ref{code:man:pgrule2}) are
used to assign specific roles to the worker agents. In particular,
the first PG-rule covers the following situation. If the manager
believes there is a bomb at a certain position for which no agent is
asked to carry it and there is a worker agent without any role
assignment, then the manager sends a message to the worker agent
asking the worker to carry the bomb, i.e., the manager asks the
worker agent to play the carrier role. After sending the message,
the manager updates its administration with the fact that there is a
role assigned to the worker. The second PG-rule asks a worker that
has no role assignment to explore a bomb if the manager has no
information about bombs.

The three PC-rules (lines
\ref{code:man:pcrule1}-\ref{code:man:pcrule3}) are used to process
the incoming messages. The messages are expected to be received from
the worker agents who play the carrier or explorer roles. In
particular, the first PC-rule (line \ref{code:man:pcrule1}) handles
messages from explorer agents who have found bombs in the
environment. In such cases, the manager registers the information
about the found bombs and unregister the worker agents from their
explorer role such that they can be asked for playing another role.
The second and third PC-rules (line \ref{code:man:pcrule2} and
\ref{code:man:pcrule3}) handle the messages from carrier agents. The
second rule covers the situation that the carrier has successfully
carried the bomb to a safe depot and the third rule covers the case
that the role could not be played successfully. In this example, we
assume actions like picking up a bomb or dropping a bomb can fail.

\begin{figure}[H]
\begin{Verbatim}[frame=single,numbers=left,firstnumber=last,
                 numbersep=2pt,commandchars=\\\[\]]
BeliefUpdates:
  { true }  SetAssigned(POS, A)     { assigned(POS, A) }
  { true }  SetBomb(POS)            { bomb(POS) }
  { true }  RemoveAssigned(POS, A)  { not assigned(POS, A) }
  { true }  RemoveBomb(POS)         { not bomb(POS) }

Beliefs:
  worker(w1).
  worker(w2).
  worker(w3).

Goals:                  \label[code:man:goal]
  haveBomb

PG-rules:
  haveBomb <- bomb(POS) and not assigned(carrier(POS), _) and \label[code:man:pgrule1]
              worker(W) and not assigned(_, W) |
  { send(W, request, play(carrier, POS));
    SetAssigned(carrier(POS), W)
  }

  haveBomb <- not bomb(_) and worker(W) and not assigned( _, W) | \label[code:man:pgrule2]
  { send(W, request, play(explorer));
    SetAssigned(explorer, W)
  }

PC-rules:
  message(A, inform, _, _, bomb(POS)) <- true  |            \label[code:man:pcrule1]
  { SetBomb(POS);
    RemoveAssigned(explorer, A)
  }

  message(A, inform, _, _, done(POS)) <- true |             \label[code:man:pcrule2]
  { RemoveAssigned(carrier(POS), A);
    RemoveBomb(POS)
  }

  message(A, inform, _, _, failed(POS)) <- true |          \label[code:man:pcrule3]
  { RemoveAssigned(carrier(POS), A) }
\end{Verbatim}
\caption{The code of the manager module.}\label{fig:managercode}
\end{figure}

The worker agent, as implemented in Figure \ref{fig:workercode}, is
an agent that waits for requests to play either the explorer or the
carrier role. When it receives a request to play the explorer role
from the manager (line \ref{code:wor:exp}), it creates an explorer
module instance and executes it (line
\ref{code:wor:createexp}-\ref{code:wor:execexp}). Note that the
stopping condition of this module instance is the belief that a bomb
has been found at a certain position. When the execution of the
module instance halts, the worker agent sends the position of the
detected bomb to the manager (line \ref{code:wor:sendexp}), and
finally releases the explorer module instance (line
\ref{code:wor:releaseexp}). Note the use of variables for passing
position values. It is important to note that for the worker agent
the creation of an explorer module instance and executing it is the
same as playing the explorer role. The worker agent plays this role
until the goal of the role (i.e., finding bombs) is believed to be
achieved.

The second PC-rule of the worker agent (line \ref{code:wor:car}) is
responsible for carrying bombs by creating a carrier module instance
(line \ref{code:wor:createcar}), adding the bomb information to its
beliefs (line \ref{code:wor:updatecar}), and executing it until
either it has found the bombs (\texttt{done} condition) or an error
has occurred (\texttt{error} condition); see line
\ref{code:car:execexp}. The final lines of this code
(\ref{code:car:test}-\ref{code:car:release}) is to inform the
manager agent about the success or failure of carrying the bomb and
releasing the carrier module instance after this communication. In
other words, this second rule indicates when the worker agent should
play the carrier role.

The PG-rule of the worker agent is to allow the agent to explore the
gridworld environment by moving to arbitrary positions. The abstract
move action \ttt gotoRandomPos(15,15) \ttt is defined by means of a
PC-rule in the included \ttt moving.2apl \ttt file.

\begin{figure}[H]
\begin{Verbatim}[frame=single,numbers=left,firstnumber=last,
                 numbersep=2pt,commandchars=\\\[\]]
Include:
  moving.2apl

Beliefs:
  manager(m).

Plans:
    B(is( X, int( random( 15 ) ) ));
    B(is( Y, int( random( 15 ) ) ));
    @blockworld( enter( X, Y, blue ), _ )

PG-rules:

  /* Wander around */
  <- true |
  {
        if B(prob(0.05)) then
            gotoRandomPos(15,15)
  }

PC-rules:
  message(A, request, _, _, play(explorer)) <- manager(A) | \label[code:wor:exp]
  {
    create(explorer, myexp);            \label[code:wor:createexp]
    myexp.execute(B(bomb(POS)));        \label[code:wor:execexp]
    send(A, inform, bomb(POS));         \label[code:wor:sendexp]
    release(myexp)                      \label[code:wor:releaseexp]
  }

  message(A, request, _, _, play(carrier, POS)) <- manager(A) | \label[code:wor:car]
  {
    create(carrier, mycar);             \label[code:wor:createcar]
    mycar.updateBB(bomb(POS));          \label[code:wor:updatecar]
    mycar.execute(B(done or error));    \label[code:car:execexp]
    if mycar.B( done ) then             \label[code:car:test]
    {
        send(A, inform, done(POS))
    }
    else
    {
      send(A, inform, failed(POS))
    };
    release(mycar)                      \label[code:car:release]
  }
\end{Verbatim}
\caption{The code of the worker module.}\label{fig:workercode}
\end{figure}

The explorer module (i.e., the implementation of the explorer role),
as implemented in Figure \ref{fig:explorercode}, has the goal to
find bombs (line \ref{code:exp:goal}). In order to achieve this
goal, it proceeds to a random location in the gridworld, performs a
sense bomb action there and, if successful, adds the position of the
detected bomb to its own local beliefs (line \ref{code:exp:pos}).
Note that this belief information satisfies the stopping condition
of the module instance (see line \ref{code:wor:execexp}) since the
goal \texttt{foundBomb} is achieved as soon as \ttt{bomb(POS)} is
added to its beliefs (line \ref{code:foundgoal}).

\begin{figure}[H]
\begin{Verbatim}[frame=single,numbers=left,firstnumber=last,
                 numbersep=2pt,commandchars=\\\[\]]
Include:
  moving.2apl

BeliefUpdates:
  { true }               RememberBomb(POS)    { bomb(POS) }
  { at(OLDPOS) }         UpdatePosition(POS)  { not at(OLDPOS), at(POS) }
  { true }               UpdatePosition(POS)  { at(POS) }

Beliefs:
  foundBomb :- bomb(_).             \label[code:foundgoal]
  prob(P) :- is(X, rand), X < P.

Goals:
  foundBomb                         \label[code:exp:goal]

PG-rules:
  /* Wander around */
  foundBomb <- prob(0.05) |
  {
        gotoRandomPos(15,15)
  }

  foundBomb <- true |
  {
    @blockworld( senseBombs(), BOMBS );
    if B( BOMBS = [actionresult([ [default,X1,Y1] | REST ])]) then
    {
       RememberBomb([X1,Y1])        \label[code:exp:pos]
    }
  }
\end{Verbatim}
\caption{The code of the explorer module.}\label{fig:explorercode}
\end{figure}

Finally, the carrier module (i.e., the implementation of the carrier
role) as implemented in Figure \ref{fig:carriercode} has a goal to
store a bomb (line \ref{code:car:goals}). If the agent is at the
same position as the bomb, then the goal can be achieved by picking
up the bomb, storing it in the depot, and removing that bomb from
its own local beliefs (lines
\ref{code:car:begr2}-\ref{code:car:endr2}). Note that the removal of
the bomb by the belief update action \ttt RemoveBomb(POS) \ttt will
imply that the job of carrying and storing the bomb is done (see
line \ref{code:car:bel}), which in turn satisfies the stopping
condition of the carrier module instance (see line
\ref{code:car:execexp}). However, if the agent is not at the bomb's
position, then it will try to modify its position. If the new
position is again not the same as the bomb's position, then it will
adopt a goal to be at that position. This is done by the first
PG-rule (lines \ref{code:car:begr1}-\ref{code:car:endr1}). The third
and fourth PG-rules (lines \ref{code:car:r3} and \ref{code:car:r4}) are to drop the carrying bomb at the safe
location (i.e., \ttt trap \ttt position). The final PR-rules (lines \ref{code:car:pr1} and \ref{code:car:pr2}) are for
the case that the pickup and drop actions fail. In these cases, the
beliefs is updated with an error message which will satisfy the
stopping condition of the carrier module instance (see line
\ref{code:car:execexp}). It is also important to note
that it is up to the gridworld programmer to determine when the
execution of a gridworld action fails.

\begin{figure}[H]
\begin{Verbatim}[frame=single,numbers=left,firstnumber=last,
                 numbersep=2pt,commandchars=\\\[\]]
Include:
    moving.2apl

BeliefUpdates:
  { true }               RemoveBomb(POS)      { not bomb(POS) }
  { not carrying_bomb }  SetCarryingBomb()    { carrying_bomb }
  { carrying_bomb }      SetNotCarryingBomb() { not carrying_bomb }
  { }                    SetError()           { error }

Beliefs:
  trap([0,0]).
  bombStored :- not bomb(_), not carrying_bomb.
  done :- bombStored.       \label[code:car:bel]

Goals:
  bombStored                \label[code:car:goals]

PG-rules:
  bombStored <- bomb(POS) and not carrying_bomb and not at(POS) | \label[code:car:begr1]
  { updatePosition();
    if B(bomb(POS) and not at(POS)) then
        adopta(at(POS))
  }                                                             \label[code:car:endr1]

  bombStored <- bomb(POS) and not carrying_bomb and at(POS) |   \label[code:car:begr2]
  {
    updatePosition();
    if B(at(POS)) then
        {   @blockworld( pickup(), _ );
            SetCarryingBomb();
            RemoveBomb(POS)
        }
  }                                                             \label[code:car:endr2]

  bombStored <- carrying_bomb and trap(TRAPPOS) and not at(TRAPPOS) |  \label[code:car:r3]
  { adopta(at(TRAPPOS)) }

  bombStored <- carrying_bomb and trap(TRAPPOS) and at(TRAPPOS) | \label[code:car:r4]
  { @blockworld( drop(), _ );
    SetNotCarryingBomb()
  }

PR-rules:
  @blockworld(pickup(), _); REST <- true  |  { SetError() } \label[code:car:pr1]
  @blockworld(drop(), _); REST   <- true  |  { SetError() } \label[code:car:pr2]
\end{Verbatim}
\caption{The code of the carrier module.}\label{fig:carriercode}
\end{figure}

The file \ttt moving.2apl \ttt contains codes for implementing the
movement of the working agents.
\end{subsection}

\end{section}

\end{chapter}
